<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>保存一个文档到集合</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="mongocollection.remove.html">MongoCollection::remove</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="mongocollection.setreadpreference.html">MongoCollection::setReadPreference</a></div>
 <div class="up"><a href="class.mongocollection.html">MongoCollection</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongocollection.save" class="refentry">
 <div class="refnamediv">
  <h1 class="refname">MongoCollection::save</h1>
  <p class="verinfo">(PECL mongo &gt;=0.9.0)</p><p class="refpurpose"><span class="refname">MongoCollection::save</span> &mdash; <span class="dc-title">保存一个文档到集合</span></p>

 </div>

 <div class="refsect1 description" id="refsect1-mongocollection.save-description">
  <h3 class="title">说明</h3>
  <div class="methodsynopsis dc-description">
   <span class="modifier">public</span> <span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <span class="methodname"><strong>MongoCollection::save</strong></span>
    ( <span class="methodparam"><span class="type"><span class="type array|object">array|object</span></span> <code class="parameter">$a</code></span>
   [, <span class="methodparam"><span class="type">array</span> <code class="parameter">$options</code><span class="initializer"> = array()</span></span>
  ] )</div>

  <p class="para rdfs-comment">
   如果对象来自数据库，则更新现有的数据库对象，否则插入对象。
  </p>
 </div>


 <div class="refsect1 parameters" id="refsect1-mongocollection.save-parameters">
  <h3 class="title">参数</h3>    
  <p class="para">
   <dl>

    
     <dt>

      <em><code class="parameter">a</code></em>
     </dt>

     <dd>

      <p class="para">
       要保存的 Array 或 Object。
       如果用的是 Object，它不能有 protected
       或 private 的属性。
      </p>
      <blockquote class="note"><p><strong class="note">Note</strong>: 
       <p class="para">
        如果参数不具有 <em>_id</em> 的键或者属性，将会创建并赋值一个新的
        <a href="class.mongoid.html" class="classname">MongoId</a> 实例。
        关于此行为的更多信息，参见 <span class="function"><a href="mongocollection.insert.html" class="function">MongoCollection::insert()</a></span>。
       </p>
      </p></blockquote>
     </dd>

    
    
     <dt>

      <em><code class="parameter">options</code></em>
     </dt>

     <dd>

      <p class="para">
       此次保存的选项。
       <ul class="itemizedlist">
        <li class="listitem"><p class="para"><em>&quot;w&quot;</em></p><p class="para">See <a href="mongo.writeconcerns.html" class="link">WriteConcerns</a>. The default value for <a href="class.mongoclient.html" class="classname">MongoClient</a> is <em>1</em>.</p></li>
        <li class="listitem"><p class="para"><em>&quot;fsync&quot;</em></p><p class="para">Boolean, defaults to <strong><code>FALSE</code></strong>. Forces the insert to be synced to disk before returning success. If <strong><code>TRUE</code></strong>, an acknowledged insert is implied and will override setting <em>w</em> to <em>0</em>.</p></li>
        <li class="listitem"><p class="para"><em>&quot;timeout&quot;</em></p><p class="para">Integer, defaults to <em>MongoCursor::$timeout</em>.  If &quot;safe&quot; is set, this sets how long (in milliseconds) for the client to wait for a database response.  If the database does not respond within the timeout period, a <a href="class.mongocursortimeoutexception.html" class="classname">MongoCursorTimeoutException</a> will be thrown.</p></li>
        <li class="listitem"><p class="para"><em>&quot;safe&quot;</em></p><p class="para"><em class="emphasis">Deprecated</em>. Please use the <a href="mongo.writeconcerns.html" class="link">WriteConcern</a> <em>w</em> option.</p></li>
       </ul>
      </p>
     </dd>

       
   </dl>

  </p>
 </div>


 <div class="refsect1 returnvalues" id="refsect1-mongocollection.save-returnvalues">
  <h3 class="title">返回值</h3>
  <p class="para">
   如果设置了 <em><code class="parameter">w</code></em>，返回包含此次保存状态的一个 array。
   否则，返回一个 boolean，表示数组是否为空（空数组不会被插入）。
  </p>
 </div>


 <div class="refsect1 errors" id="refsect1-mongocollection.save-errors">
  <h3 class="title">错误／异常</h3>
  <p class="para">
   如果插入的文档时空的，或者包含零长度的键，将抛出 <a href="class.mongoexception.html" class="classname">MongoException</a>。
   尝试插入包含 protected 和 private 属性的对象将导致零长度键的错误。
  </p>
  <p class="para">Throws <a href="class.mongocursorexception.html" class="classname">MongoCursorException</a> if the &quot;w&quot; option is set and the write fails.</p><p class="para">Throws <a href="class.mongocursortimeoutexception.html" class="classname">MongoCursorTimeoutException</a> if the &quot;w&quot; option is set to a value greater than one and the operation takes longer than <var class="varname"><var class="varname">MongoCursor::$timeout</var></var> milliseconds to complete.  This does not kill the operation on the server, it is a client-side timeout. The operation in <em>MongoCollection::$wtimeout</em> is milliseconds.</p>
 </div>


 <div class="refsect1 changelog" id="refsect1-mongocollection.save-changelog">
  <h3 class="title">更新日志</h3>
  <p class="para">
   <table class="doctable informaltable">
    
     <thead>
      <tr>
       <th>版本</th>
       <th>说明</th>
      </tr>

     </thead>

     <tbody class="tbody">
      <tr>
       <td>1.2.0</td>
       <td>增加 <em>&quot;timeout&quot;</em> 选项。</td>
      </tr>

      <tr>
       <td>1.0.11</td>
       <td>
        设置 <em>&quot;safe&quot;</em> 时，当出现 &quot;not master&quot; 错误时主动断开连接。
       </td>
      </tr>

      <tr>
       <td>1.0.9</td>
       <td>
        <p class="para">
        选项 <em>&quot;safe&quot;</em> 接受 integer 的值，之前仅仅接受 boolean。
        </p>
        <p class="para">
         增加 <em>&quot;fsync&quot;</em> 选项。
        </p>
       </td>
      </tr>

      <tr>
       <td>1.0.5</td>
       <td>增加 <em><code class="parameter">options</code></em> 参数。</td>
      </tr>

     </tbody>
    
   </table>

  </p>
 </div>


 <div class="refsect1 examples" id="refsect1-mongocollection.save-examples">
  <h3 class="title">范例</h3>
  <div class="example" id="example-1435">
   <p><strong>Example #1 <span class="function"><strong>MongoCollection::save()</strong></span> 例子</strong></p>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br />$obj&nbsp;</span><span style="color: #007700">=&nbsp;array(</span><span style="color: #DD0000">'x'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">//&nbsp;插入&nbsp;$obj&nbsp;到&nbsp;db<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">save</span><span style="color: #007700">(</span><span style="color: #0000BB">$obj</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$obj</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">//&nbsp;增加额外的字段<br /></span><span style="color: #0000BB">$obj</span><span style="color: #007700">[</span><span style="color: #DD0000">'foo'</span><span style="color: #007700">]&nbsp;=&nbsp;</span><span style="color: #DD0000">'bar'</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">//&nbsp;$obj&nbsp;不能被再次插入，导致&nbsp;duplicate&nbsp;_id&nbsp;错误<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$obj</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">//&nbsp;保存、更新附带新字段的&nbsp;$obj<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">save</span><span style="color: #007700">(</span><span style="color: #0000BB">$obj</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

   <div class="example-contents"><p>以上例程的输出类似于：</p></div>
   <div class="example-contents screen">
<div class="cdata"><pre>
array(2) {
  [&quot;x&quot;]=&gt;
  int(1)
  [&quot;_id&quot;]=&gt;
  object(MongoId)#4 (1) {
    [&quot;$id&quot;]=&gt;
    string(24) &quot;50b6afe544415ed606000000&quot;
  }
}
</pre></div>
   </div>
  </div>
 </div>


</div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="mongocollection.remove.html">MongoCollection::remove</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="mongocollection.setreadpreference.html">MongoCollection::setReadPreference</a></div>
 <div class="up"><a href="class.mongocollection.html">MongoCollection</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
